home *** CD-ROM | disk | FTP | other *** search
/ Power Utilities / Power Utilities.iso / utility / pro65 / scsaver.api < prev    next >
Encoding:
Text File  |  1993-01-01  |  15.2 KB  |  396 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.        ________________________
  9.        \                     \ \
  10.         \       Tom           \ \
  11.          \       Donnelly      \ \
  12.           \       Computer      \ \
  13.            \       Software      \ \
  14.             \_____________________\_\
  15.              \_____________________\_\
  16.  
  17.  
  18.  
  19.  
  20.  
  21.  
  22.                                                            Screen Saver
  23.                                                             Version 5.1
  24.  
  25.                                    Screen blanker and security software
  26.  
  27.                           APPLICATION PROGRAMMING INTERFACE DESCRIPTION
  28.  
  29.  
  30.  
  31.                                                            Tom Donnelly
  32.                                                       Computer Software
  33.                                                           P.O. Box 3856
  34.                                                           San Dimas, CA
  35.                                                                   91773
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.  
  45.  
  46.  
  47.  
  48.  
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.       Copyright (C) 1992-1993  Tom R. Donnelly  All Rights Reserved
  56.  
  57. APPLICATION PROGRAMMING INTERFACE DESCRIPTION                       ...1
  58. ========================================================================
  59.  
  60.  
  61.    This document describes the protocol required by a user application
  62.    program to communicate with the resident copy of Screen Saver.  Using
  63.    this interface, it is possible to change various parameters of the
  64.    resident program from within a user application.
  65.  
  66.    The information provided in this document is subject to change
  67.    without notice.
  68.  
  69.    All communication between a user application and Screen Saver is
  70.    performed through DOS Interrupt 54h.  Using this interrupt, an
  71.    application can interrogate whether Screen Saver is resident, which
  72.    version is running and the segment address at which it was loaded.
  73.    The application may also read and/or update the status byte, used to
  74.    control certain Screen Saver options.
  75.  
  76.    Before issuing any calls to Screen Saver, you must insure that the
  77.    vector for interrupt 54h is not zero.  If it is zero, then Screen
  78.    Saver is not resident.  Issuing INT 54h when the vector is zero will
  79.    send your computer into hyperspace, forcing a cold-boot.
  80.  
  81.               Mov   AX,3554h      ;Get interrupt vectors in ES:BX
  82.               Int   21h           ;Call DOS
  83.               Or    BX,BX         ;Any offset?
  84.               Jz    Not_resident  ;No - not resident
  85.               Mov   BX,ES         ;Copy segment
  86.               Or    BX,BX         ;Any segment?
  87.               Jz    Not_resident  ;No - not resident
  88.  
  89.    After determining that the INT 54h vector points to something, the
  90.    program is free to make function calls.  All function calls require
  91.    the function number in the AH register, the component code in AL
  92.    register (Screen Saver's Activity Monitor component code is 03h, the
  93.    Event Logger's component code is 18h) and the characters 'TD' in the
  94.    CX register.  Some functions, such as ReplaceStatusByte, require a
  95.    new status byte in the BL register.
  96.  
  97.    If the function call was successful, CX will be returned containing
  98.    zero (otherwise, CX will be non-zero).  Byte parameters will usually
  99.    be returned in the AL register.  The GetLoadAddr function returns the
  100.    segment address in the ES register.
  101.  
  102.                              *** IMPORTANT ***
  103.  
  104.    Screen Saver is not the only program to use the INT 54h interface.
  105.    It is important to check the success of the function call even when
  106.    you find INT 54h to be non-zero.  Screen Saver will only answer
  107.    function calls containing the correct component code (03h for the
  108.    Activity Monitor, 18h for the Event Logger) in AL.  In addition,
  109.    there may be function calls which are not supported on older versions
  110.    of Screen Saver.  Issuing an unsupported function call will return a
  111.    non-zero value in the CX register.
  112.  
  113.  
  114. APPLICATION PROGRAMMING INTERFACE DESCRIPTION - ACTIVITY MONITOR    ...2
  115. ========================================================================
  116.  
  117.  
  118.    Function 0 - GetVersion
  119.       Entry:  AH=0        Function code
  120.               AL=03h      Component code (always 3 for Activity Monitor)
  121.               CX='TD'     Literal
  122.  
  123.       Exit:   CX=0        If Screen Saver Activity Monitor is resident.
  124.               AL=version  Format is Major*10 + Minor, eg: Version 4.9
  125.                           is returned as 49 (decimal) or 31h.
  126.  
  127.    ---------------------------------------------------------------------
  128.  
  129.    Function 3 - GetState
  130.       Entry:  AH=3        Function code
  131.               AL=03h      Component code (always 3 for Activity Monitor)
  132.               CX='TD'     Literal
  133.  
  134.       Exit:   CX=0        If Activity Monitor is resident.
  135.               AL=1        If Activity Monitor is ON or ON with LOCK.
  136.               AL=0        If Activity Monitor is OFF.
  137.  
  138.    ---------------------------------------------------------------------
  139.  
  140.    Function 4 - Disable (deactivate Screen Saver Activity Monitor)
  141.       Entry:  AH=4        Function code
  142.               AL=03h      Component code (always 3 for Activity Monitor)
  143.               CX='TD'     Literal
  144.  
  145.       Exit:   CX=0        If Screen Saver Activity Monitor is resident.
  146.  
  147.    ---------------------------------------------------------------------
  148.  
  149.    Function 5 - Enable (reactivate Screen Saver Activity Monitor)
  150.       Entry:  AH=5        Function code
  151.               AL=03h      Component code (always 3 for Activity Monitor)
  152.               CX='TD'     Literal
  153.  
  154.       Exit:   CX=0        If Screen Saver Activity Monitor is resident.
  155.  
  156.    ---------------------------------------------------------------------
  157.  
  158.    Function 7 - GetLoadAddr
  159.       Entry:  AH=7        Function code
  160.               AL=03h      Component code (always 3 for Activity Monitor)
  161.               CX='TD'     Literal
  162.  
  163.       Exit:   CX=0        If Screen Saver Activity Monitor is resident.
  164.               ES=         Segment address of resident code.
  165.  
  166.  
  167. APPLICATION PROGRAMMING INTERFACE DESCRIPTION - ACTIVITY MONITOR    ...3
  168. ========================================================================
  169.  
  170.  
  171.  
  172.    Function 8 - GetStatusByte
  173.       Entry:  AH=8        Function code
  174.               AL=03h      Component code (always 3 for Activity Monitor)
  175.               CX='TD'     Literal
  176.  
  177.       Exit:   CX=0        If Screen Saver Activity Monitor is resident.
  178.               AL=76543210 Status byte from resident code.
  179.                           Bit 7:  1=EGA supported (do not change)
  180.                           Bit 6:  1=VGA supported (do not change)
  181.                           Bit 5:  1=MCGA supported (do not change)
  182.                           Bit 4:  1=Hercules supported (do not change)
  183.                           Bit 3:  1=Invoke keyboard lock
  184.                           Bit 2:  1=Invoke screen blanker
  185.                           Bit 1:  1=Lock-mode active (LOCK or LOCKONLY)
  186.                           Bit 0:  1=Blanker active (ON or LOCK mode)
  187.  
  188.    ---------------------------------------------------------------------
  189.  
  190.    Function 9 - ReplaceStatusByte
  191.       Entry:  AH=9        Function code
  192.               AL=03h      Component code (always 3 for Activity Monitor)
  193.               BL=byte     new status byte (See Function 8 for details)
  194.               CX='TD'     Literal
  195.  
  196.       Exit:   CX=0        If Screen Saver Activity Monitor is resident.
  197.  
  198.  
  199. APPLICATION PROGRAMMING INTERFACE DESCRIPTION - ACTIVITY MONITOR    ...4
  200. ========================================================================
  201.  
  202.  
  203.    Example:  Activate security lock from an application program.
  204.  
  205.              This code fragment performs the following:
  206.                 1. Insures that vectors for INT 54h is not zero.
  207.                 2. Requests the resident version to make sure that
  208.                    Screen Saver is resident and that it is at least
  209.                    version 5.1.
  210.                 3. Requests the resident status byte.
  211.                 4. Turns on the lock-request bit in the status byte.
  212.                 5. Replaces the status byte in the resident code.
  213.  
  214.  
  215.               Mov   AX,3554h      ;Get interrupt vectors in ES:BX
  216.               Int   21h           ;Call DOS
  217.               Or    BX,BX         ;Any offset?
  218.               Jz    NotResident   ;No - not resident
  219.               Mov   BX,ES         ;Copy segment
  220.               Or    BX,BX         ;Any segment?
  221.               Jz    NotResident   ;No - not resident
  222.  
  223.               Mov   AH,0          ;GetVersion function code
  224.               Mov   AL,3          ;Component code
  225.               Mov   CX,'TD'       ;Literal
  226.               Int   54h
  227.               Jcxz  GotVersion    ;Got it ok
  228.               Jmp   NotResident
  229.        GotVersion:
  230.               Cmp   AL,51         ;Version 5.1 or greater?
  231.               Jb    BadVersion    ;No - skip the rest
  232.  
  233.               Mov   AH,8          ;GetStatusByte function code
  234.               Mov   AL,3          ;Component code
  235.               Mov   CX,'TD'       ;Literal
  236.               Int   54h
  237.               Jcxz  GotStatus     ;Got it ok
  238.               <Handle error here>
  239.        GotStatus:
  240.               Or    AL,00001010b  ;Insure lock mode and activate lock
  241.  
  242.               Mov   BL,AL         ;copy to BL for Replace function
  243.               Mov   AH,9          ;ReplaceStatusByte function code
  244.               Mov   AL,3          ;Component code
  245.               Mov   CX,'TD'       ;Literal
  246.               Int   54h
  247.               Jcxz  AllDone
  248.               <Handle error here>
  249.        AllDone:
  250.  
  251. APPLICATION PROGRAMMING INTERFACE DESCRIPTION - EVENT LOGGER        ...5
  252. ========================================================================
  253.  
  254.  
  255.    Function 0 - GetVersion
  256.       Entry:  AH=0        Function code
  257.               AL=18h      Component code (always 18h for Event Logger)
  258.               CX='TD'     Literal
  259.  
  260.       Exit:   CX=0        If Screen Saver Event Logger is resident.
  261.               AL=version  Format is Major*10 + Minor, eg: Version 4.9
  262.                           is returned as 49 (decimal) or 31h.
  263.  
  264.    ---------------------------------------------------------------------
  265.  
  266.    Function 2 - ReplaceParm
  267.       Entry:  AH=2        Function code
  268.               AL=18h      Component code (always 18h for Event Logger)
  269.               CX='TD'     Literal
  270.               BX=code     Event code to be logged
  271.                           0000h=Keyboard unlocked
  272.                           0001h=Invalid Password
  273.                           0002h=Lock-engaged
  274.                           0003h=Midnight
  275.                           0004h=SCSAVER loaded
  276.                           0005h=SCSAVER removed
  277.                           0006h=SCSAVER updated resident parameters
  278.                           0007h=New password set
  279.                           0008h=Clear counters
  280.                           0009h=Enable logging
  281.                           000Ah-
  282.                           007Fh=Reserved
  283.                           0080h-
  284.                           00FFh=User log events
  285.  
  286.       Exit:   CX=0        If Event Logger is resident.
  287.               AL=1        If Event Logger is logging events.
  288.               AL=0        If Event Logger is deferring events.
  289.  
  290.    ---------------------------------------------------------------------
  291.  
  292.    Function 3 - GetState
  293.       Entry:  AH=3        Function code
  294.               AL=18h      Component code (always 18h for Event Logger)
  295.               CX='TD'     Literal
  296.  
  297.       Exit:   CX=0        If Event Logger is resident.
  298.               AL=1        If Event Logger is logging events.
  299.               AL=0        If Event Logger is deferring events.
  300.  
  301.  
  302. APPLICATION PROGRAMMING INTERFACE DESCRIPTION - EVENT LOGGER        ...6
  303. ========================================================================
  304.  
  305.  
  306.  
  307.    Function 4 - Disable (defer Screen Saver Event Logger)
  308.       Entry:  AH=4        Function code
  309.               AL=18h      Component code (always 18h for Event Logger)
  310.               CX='TD'     Literal
  311.  
  312.       Exit:   CX=0        If Screen Saver Event Logger is resident.
  313.  
  314.    ---------------------------------------------------------------------
  315.  
  316.    Function 5 - Enable (reactivate Screen Saver Event Logger)
  317.       Entry:  AH=5        Function code
  318.               AL=18h      Component code (always 18h for Event Logger)
  319.               CX='TD'     Literal
  320.  
  321.       Exit:   CX=0        If Screen Saver Event Logger is resident.
  322.  
  323.    ---------------------------------------------------------------------
  324.  
  325.    Function 7 - GetLoadAddr
  326.       Entry:  AH=7        Function code
  327.               AL=18h      Component code (always 18h for Event Logger)
  328.               CX='TD'     Literal
  329.  
  330.       Exit:   CX=0        If Screen Saver Event Logger is resident.
  331.               ES=         Segment address of resident code.
  332.  
  333.    ---------------------------------------------------------------------
  334.  
  335.    Function 8 - GetStatusByte
  336.       Entry:  AH=8        Function code
  337.               AL=18h      Component code (always 18h for Event Logger)
  338.               CX='TD'     Literal
  339.  
  340.       Exit:   CX=0        If Screen Saver Event Logger is resident.
  341.               AL=76543210 Status byte from resident code.
  342.                           Bit 7-1: Reserved
  343.                           Bit 0:   1=Event logging active
  344.  
  345.    ---------------------------------------------------------------------
  346.  
  347.    Function 9 - ReplaceStatusByte
  348.       Entry:  AH=9        Function code
  349.               AL=18h      Component code (always 18h for Event Logger)
  350.               BL=byte     new status byte (See Function 8 for details)
  351.               CX='TD'     Literal
  352.  
  353.       Exit:   CX=0        If Screen Saver Event Logger is resident.
  354.  
  355.  
  356. APPLICATION PROGRAMMING INTERFACE DESCRIPTION - EVENT LOGGER        ...7
  357. ========================================================================
  358.  
  359.  
  360.    Example:  Clear Event Logger counters from an application program.
  361.  
  362.              This code fragment performs the following:
  363.                 1. Insures that vectors for INT 54h is not zero.
  364.                 2. Requests the resident version to make sure that
  365.                    Screen Saver is resident and that it is at least
  366.                    version 5.1.
  367.                 3. Issue the Clear Counter request.
  368.  
  369.  
  370.               Mov   AX,3554h      ;Get interrupt vectors in ES:BX
  371.               Int   21h           ;Call DOS
  372.               Or    BX,BX         ;Any offset?
  373.               Jz    NotResident   ;No - not resident
  374.               Mov   BX,ES         ;Copy segment
  375.               Or    BX,BX         ;Any segment?
  376.               Jz    NotResident   ;No - not resident
  377.  
  378.               Mov   AH,0          ;GetVersion function code
  379.               Mov   AL,18h        ;Component code
  380.               Mov   CX,'TD'       ;Literal
  381.               Int   54h
  382.               Jcxz  GotVersion    ;Got it ok
  383.               Jmp   NotResident
  384.        GotVersion:
  385.               Cmp   AL,51         ;Version 5.1 or greater?
  386.               Jb    BadVersion    ;No - skip the rest
  387.  
  388.               Mov   AH,2          ;ReplaceParm function code
  389.               Mov   AL,18h        ;Component code
  390.               Mov   CX,'TD'       ;Literal
  391.               Mov   BX,8          ;Clear counters
  392.               Int   54h
  393.               Jcxz  AllDone
  394.               <Handle error here>
  395.        AllDone:
  396.